REST API exploration using jq

REST APIs are one of the building blocks of the modern Internet, and most organisations use them to some extent. This means that they are a great source of data – and where there’s data, there’s a use case for Splunk! In this post, we will use the Salesforce status page as an example, but this can be applied to any API you can think of.

Before you can ingest the data from the API, you’ll want to investigate it. This can be done using a simple curl command with the url of the API, which will return a chunk of JSON formatted data. Using “2>/dev/null” with this command will filter out any errors.

curl https://api.status.salesforce.com/v1/instances/EU32/status 2>/dev/null

As you can see, the result of that curl command is a huge chunk of text that is difficult to read. Luckily, a tool exists to make this easier on the eyes. jq is a simple utility that processes JSON in the command line. Once you have installed jq, getting readable output from a curl command is simple:

curl https://api.status.salesforce.com/v1/instances/EU32/status 2>/dev/null | jq

Now that you can read the JSON, you might notice that you only want to see part of the output – jq also allows you to extract specific parts of the data, which you can do by including a path to that part of the JSON:

curl https://api.status.salesforce.com/v1/instances/EU32/status 2>/dev/null | jq '.Incidents[]'

Or even more simply, you can query one specific line of the JSON:

curl https://api.status.salesforce.com/v1/instances/EU32/status 2>/dev/null | jq '.status'

Once you’ve explored the API and know which parts of it you want to use, you are ready to ingest it into Splunk. There are several ways to do this, such as using a scripted input.